Skip to content

Add AGENTS.md for coding agents - #120

Merged
JongChern merged 3 commits into
masterfrom
docs/agents-md
Oct 20, 2026
Merged

JongChern merged 3 commits into
masterfrom
docs/agents-md

Conversation

@marknolan

@marknolan marknolan commented Sep 30, 2026 •

Copy link
Copy Markdown
Member

Adds AGENTS.md, matching the twelve other Shimmer repos that now carry one. CLAUDE.md is a one-line @AGENTS.md import so Claude Code picks the same file up — the content is not duplicated.

Docs only; no build or source files are touched.

What it records

The repo is straightforward to read, so the file sticks to things that are not evident from the source:

It wraps the driver, it does not reimplement it. Shimmer, Shimmer4Android and VerisenseDeviceAndroid extend ShimmerBluetooth, Shimmer4sdk and VerisenseDevice from Shimmer-Java-Android-API. There is no wire-format, parsing, calibration or timestamp logic here, so a protocol fix belongs upstream and never needs re-writing in this repo. Grepping for calibrat or timeStamp does hit Shimmer.java, but only in changelog comments and in reads of already-calibrated ObjectCluster data.

Upstream fixes do not arrive automatically. The driver comes in as version-pinned Maven artifacts from GitHub Packages, injected into every subproject by the root build.gradle. A fix upstream reaches Android only once it is republished and the pin bumped:

pinned here source in Shimmer-Java-Android-API published
shimmerdriver 0.11.7_beta 0.11.8_beta 0.11.8_beta (2026-08-05)
shimmerbluetoothmanager 0.11.7_beta 0.11.8_beta 0.11.7_beta only

shimmerbluetoothmanager 0.11.8_beta appears never to have been published, so the pin cannot be bumped as things stand. Raised as DEV-1115 — this PR only documents the situation.

Build facts that cost time otherwise:

  • the build root is ShimmerAndroidInstrumentDriver/ (where settings.gradle is), not the repo root, and a same-named library module nests inside it
  • both wrapper directories carry a Gradle wrapper, at different versions — 8.5 at the build root, 8.14.3 in the module. Gradle walks upward for settings.gradle, so the inner one builds the same project with a different Gradle
  • a PAT with read:packages is needed in ~/.gradle/gradle.properties as gpr.usr/gpr.key, or resolution fails in a way that reads like a network fault rather than a missing credential. The property is gpr.usr; a commented-out block in the module says gpra.usr, which is dead code
  • there is no CI — no workflows at all, so nothing here is compiled on push or PR

The README links point at a retired org. Every link targets ShimmerEngineering/ShimmerAndroidAPI and survives only on GitHub's rename redirect. Noted rather than changed, to keep this PR to one thing.

Checking it

Claims about the class hierarchy and the pins are all readable in this tree; the published-version column came from the org package listing:

gh api orgs/ShimmerResearch/packages/maven/com.shimmerresearch.shimmerbluetoothmanager/versions --jq '.[0:3][].name'

🤖 Generated with Claude Code

AGENTS.md is the vendor-neutral convention read by Cursor, Copilot, Codex and
others. CLAUDE.md is a one-line import of it, so Claude Code picks it up too
without the content being duplicated.

Records the things that are not evident from the source:

- this repo wraps Shimmer-Java-Android-API and holds no wire-format, parsing,
  calibration or timestamp logic of its own, so protocol fixes belong upstream
- the driver arrives as version-pinned GitHub Packages artifacts, so an upstream
  fix only lands here once it is republished and the pin is bumped, and the pins
  are currently a release behind
- the build root is ShimmerAndroidInstrumentDriver/, not the repo root, and a
  same-named module nests inside it
- the two Gradle wrappers are at different versions (8.5 and 8.14.3)
- a PAT with read:packages is required in ~/.gradle/gradle.properties as
  gpr.usr/gpr.key, or dependency resolution fails in a way that reads like a
  network fault
- there is no CI, so nothing here is compiled on push or PR
- the README links all target the retired ShimmerEngineering org

Docs only. No build or source files are touched.

Co-Authored-By: Claude Opus 5 <[email protected]>
AGENTS.md said this repo has no parsing logic of its own, so a protocol
fix never needs porting here. That is wrong for the Bluetooth stream
parser. Shimmer overrides processPacket(), processWhileStreaming(),
processInstreamResponse() and clearSingleDataPacketFromBuffers() from the
driver's ShimmerBluetooth, so a streaming-parse fix in the driver never
reaches it, even after a republish and pin bump. The bare-ACK link-CRC
fix in ShimmerResearch/Shimmer-Java-Android-API#319 is one that needs its
own port.

Decoding (processDataPacket() -> buildMsg()) and checkCrc() are still the
driver's, and Shimmer3BLEAndroid uses the driver's parser. The section
now says both.

Verified on master 44b9cbc against the pinned driver, API_v0.11.7_beta.
Docs only.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@marknolan

Copy link
Copy Markdown
Member Author

Corrected the "It wraps the driver" section in ad9aa5c.

It said this repo has no parsing logic of its own. That is wrong for the Bluetooth stream parser: Shimmer.java overrides processPacket(), processWhileStreaming(), processInstreamResponse() and clearSingleDataPacketFromBuffers() from ShimmerBluetooth, so a streaming-parse fix in the driver never reaches it, even after a republish and pin bump. For example, the bare-ACK link-CRC fix in ShimmerResearch/Shimmer-Java-Android-API#319 needs its own port here (#121).

Decoding (processDataPacket() → buildMsg()) and checkCrc() are still the driver's, and the section now says that too. This supersedes the matching paragraph in the description above.

Merge order: #121 adds a temporary checkCrc() override to Shimmer.java, so whichever of #120 and #121 merges second should update that line.

ad9aa5c corrected the wrapper claim as of master. This brings it up to
DEV-1148 (#121) and fills gaps in the build notes:

- checkCrc() is overridden too since DEV-1148, as a stopgap until the
  driver pin includes DEV-1147. The section said it was the driver's.
- readBattery() and readStatusLogAndStream() write straight to the
  socket while streaming instead of queueing, and processWhileStreaming()
  reads in bulk where the driver reads a byte at a time.
- DEV-1147's driver fix had to be ported here by hand as DEV-1148. That
  is the consequence a reader needs, so it is now said outright.
- The build root's gradle.properties is gitignored, and AGP refuses to
  build without android.useAndroidX=true. Jetifier has to stay off: it
  fails on a transitive jackson-core 2.18.2 (class file version 65).
- DEV-1148 adds JVM unit tests (JUnit 4, returnDefaultValues). The
  command that runs them is documented.
- "Java 11" was the source and target level. AGP 8 needs Gradle to run
  on JDK 17 or later.

The unit-test setup and the checkCrc() override exist only on #121's
branch, so this should merge after #121.

Docs only.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@marknolan

Copy link
Copy Markdown
Member Author

Pushed 2d14f82 on top of ad9aa5c. It brings the parser section up to DEV-1148 (#121) and fills some gaps in the build notes:

  • checkCrc() is overridden in Shimmer.java too since DEV-1148, as a stopgap until the driver pin includes DEV-1147. The section had said it was still the driver's.
  • readBattery() and readStatusLogAndStream() write straight to the socket while streaming instead of queueing, and processWhileStreaming() reads in bulk where the driver reads a byte at a time.
  • It now says outright that a driver parsing, CRC or ACK fix has to be ported by hand, as DEV-1148 did for DEV-1147 (DEV-1147: consume a bare ACK's link CRC while streaming Shimmer-Java-Android-API#319).
  • Build: the build root's gradle.properties is gitignored, and AGP refuses to build without android.useAndroidX=true. Jetifier has to stay off, because it fails on a transitive jackson-core 2.18.2 (class file version 65).
  • Unit tests: DEV-1148's JVM tests (JUnit 4, unitTests.returnDefaultValues) and the command that runs them, ./gradlew -Pandroid.useAndroidX=true :ShimmerAndroidInstrumentDriver:test from ShimmerAndroidInstrumentDriver/.
  • "Java 11" was the source and target level only. AGP 8 needs Gradle itself to run on JDK 17 or later.

Merge order: AGENTS.md now describes the checkCrc() override and the test setup, which exist only on #121's branch, so merge #121 first and then this. That replaces the "whichever merges second" note above.

@JongChern
JongChern merged commit 65a33ae into master Oct 20, 2026
@JongChern
JongChern deleted the docs/agents-md branch October 20, 2026 08:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants